home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 701-725 / 708 / intuisup / intuisup42.lha / Intuisup / Library / intuisup.doc < prev    next >
Text File  |  1992-06-23  |  18KB  |  441 lines
  1.         A few sentences to ISUP
  2.         -----------------------
  3.  
  4. All ISUP objects are created from special data structures (struct xxxData)
  5. via library functions (Createxxx). Some of these functions expect (a pointer
  6. to) an ARRAY of data structures to create multiple objects with one call.
  7. These arrays are terminated with an entry (data structure) with it's type
  8. member (xxx_Type) set to the special value INTUISUP_DATA_END (0).
  9. DON'T FORGET THIS TERMINATION ENTRY OR YOU'RE VISITED BY THE GURU.
  10.  
  11. The creation functions return a pointer (APTR) to the internal data
  12. environment according to these ISUP objects. This pointer is used later as
  13. paramter for the other functions to access the object data.
  14. THE POINTERS TO INTERNAL DATA OF THE DIFFERENT ISUP OBJECTS ARE ALL OF THE
  15. SAME TYPE (APTR), SO DON'T CONFUSE WITH THEM.
  16.  
  17. Now a few words to the functions of ISUP library:
  18.  
  19. APTR IGetRenderInfo(struct Screen  *screen, USHORT flags)
  20.     screen - ptr to screen the ISUP object should be displayed on or
  21.          NULL for the workbench screen
  22.     flags - RENDER_INFO_FLAG_xxx
  23.  
  24.     Returns a pointer to an internal data structure with some visual
  25.     infos needed for creation of ISUP objects. Use the SAME pointer
  26.     (only ONE call of IGetRenderInfo for all ISUP objects displayed on
  27.     the SAME screen) as parameter APTR ri to the ISUP functions. This
  28.     data structure MUST be released with the function IFreeRenderInfo
  29.     before closing library.
  30.  
  31. VOID IFreeRenderInfo(APTR ri)
  32.     ri - pointer to internal data structure returned by IGetRenderInfo
  33.  
  34.     Releases memory for internal data structure allocated by
  35.     IGetRenderInfo.
  36.  
  37. struct Window  *IOpenWindow(APTR ri, struct NewWindow  *nw, USHORT flags)
  38.     ri - pointer to internal data structure returned by IGetRenderInfo
  39.     nw - pointer to initialized NewWindow structure
  40.     flags - OPEN_WINDOW_FLAG_xxx
  41.  
  42.     Manipulates NewWindow structure according to given flags and opens
  43.     window from it.
  44.  
  45. VOID IClearWindow(APTR ri, struct Window  *win, USHORT left_edge,
  46.          USHORT top_edge, USHORT width, USHORT height, USHORT flags)
  47.     ri - pointer to internal data structure returned by IGetRenderInfo
  48.     win - pointer to window opened by (I)OpenWindow
  49.     left_edge, top_edge, width, height - dimension of area to clear
  50.     flags - CLEAR_WIDNOW_FLAG_xxx
  51.  
  52.     Clears area of given window according to visual infos (APTR ri). The
  53.     area will be clipped to the window dimension if necessary.
  54.  
  55. VOID ICloseWindow(struct Window  *win, BOOL more_windows)
  56.     win - pointer to window opened by (I)OpenWindow
  57.     more_windows - TRUE if user port of window shared with other windows
  58.  
  59.     Closes window in a savely manner (all IntuiMessages are replyed,
  60.     user port is only closed if not shared, ...).
  61.  
  62. struct AvailFontsHeader    *IAvailFonts(APTR ri)
  63.     ri - pointer to internal data structure returned by IGetRenderInfo
  64.  
  65.     Creates a list of all available fonts (ROM + disk) and saves this in
  66.     the internal data structure (APTR ri).
  67.  
  68. struct TextAttr  *IAskFont(APTR ri, struct TextAttr  *ta)
  69.     ri - pointer to internal data structure returned by IGetRenderInfo
  70.     ta - pointer to initialized structure with text attributes
  71.  
  72.     Check if given font exists in internal font list (APTR ri) created
  73.     with IAvailFonts.
  74.  
  75. struct TextFont  *IOpenFont(APTR ri, struct TextAttr  *ta)
  76.     ri - pointer to internal data structure returned by IGetRenderInfo
  77.     ta - pointer to initialized structure with text attributes
  78.  
  79.     Open font according to given TextAttr structure from internal font
  80.     list (APTR ri).
  81.  
  82. VOID IDisplayTexts(APTR ri, struct Window  *win, struct TextData  *td,
  83.            SHORT hoffset, SHORT voffset, BYTE **language_text_array)
  84.     ri - pointer to internal data structure returned by IGetRenderInfo
  85.     win - pointer to window opened by (I)OpenWindow
  86.     td - pointer to ARRAY of initialized TextData structures
  87.     hoffset, voffset - offsets added to positions of ALL texts
  88.     language_text_array - pointer to string pointer array created with
  89.                   IBuildLanguageTextArray or NULL
  90.  
  91.     Displays texts described in given data structure array. If given
  92.     language_text_array is not NULL then td_Text doesn't contain a
  93.     pointer to string but an offset of the string pointer in given array
  94.     with pointers to text in foreign languages.
  95.  
  96. USHORT IPrintText(APTR ri, struct Window  *win, BYTE *text, USHORT left_edge,
  97.      USHORT top_edge, USHORT type, USHORT flags, struct TextAttr  *text_attr)
  98.     ri - pointer to internal data structure returned by IGetRenderInfo
  99.     win - pointer to window opened by (I)OpenWindow
  100.     text - pointer to string with text
  101.     left_edge, top_edge - position of text on diplay
  102.     type - TEXT_DATA_TYPE_xxx
  103.     flags - TEXT_DATA_FLAG_xxx
  104.     text_attr - font used for text
  105.  
  106.     Displays text at given position.
  107.  
  108. USHORT IConvertUnsignedDec(ULONG num, BYTE *buffer, USHORT flags)
  109.     num - number to be converted
  110.     buffer - pointer to buffer for converted number
  111.     flags - CONVERT_FLAG_xxx
  112.  
  113.     Convert binary number to text string in unsigned decimal format.
  114.  
  115. USHORT IConvertSignedDec(LONG num, BYTE *buffer, USHORT flags)
  116.     num - number to be converted
  117.     buffer - pointer to buffer for converted number
  118.     flags - CONVERT_FLAG_xxx
  119.  
  120.     Convert binary number to text string in signed decimal format.
  121.  
  122. USHORT IConvertHex(ULONG num, BYTE *buffer, USHORT flags)
  123.     num - number to be converted
  124.     buffer - pointer to buffer for converted number
  125.     flags - CONVERT_FLAG_xxx
  126.  
  127.     Convert binary number to text string in hexa decimal format.
  128.  
  129. USHORT IConvertBin(ULONG num, BYTE *buffer, USHORT flags)
  130.     num - number to be converted
  131.     buffer - pointer to buffer for converted number
  132.     flags - CONVERT_FLAG_xxx
  133.  
  134.     Convert binary number to text string in binary format.
  135.  
  136. VOID IDisplayBorders(APTR ri, struct Window  *win, struct BorderData  *bd,
  137.                            SHORT hoffset, SHORT voffset)
  138.     ri - pointer to internal data structure returned by IGetRenderInfo
  139.     win - pointer to window opened by (I)OpenWindow
  140.     td - pointer to ARRAY of initialized BorderData structures
  141.     hoffset, voffset - offsets added to positions of ALL texts
  142.  
  143.     Displays borders described in given data structure array.
  144.  
  145. VOID IDrawBorder(APTR ri, struct Window  *win, USHORT left_edge,
  146.           USHORT top_edge, USHORT width, USHORT height, USHORT type)
  147.     ri - pointer to internal data structure returned by IGetRenderInfo
  148.     win - pointer to window opened by (I)OpenWindow
  149.     left_edge, top_edge, width, height - dimension of border
  150.     type - BORDER_DATA_TYPE_xxx
  151.  
  152.     Draws border at given position on display.
  153.  
  154. APTR ICreateGadgets(APTR ri, struct GadgetData  *gd, SHORT hoffset,
  155.                   SHORT voffset, BYTE **language_text_array)
  156.     ri - pointer to internal data structure returned by IGetRenderInfo
  157.     gd - pointer to ARRAY of initialized GadgetData structures
  158.     hoffset, voffset - offsets added to positions of ALL texts
  159.     language_text_array - pointer to string pointer array created with
  160.                   IBuildLanguageTextArray or NULL
  161.  
  162.     Create internal data structure for ISUP gadgets from given array of
  163.     data structures. This function DON'T display any object. Displaying
  164.     will be done with IDisplayGadgets. Internal data structure MUST be
  165.     released with IFreeGadgets. If given language_text_array are not
  166.     NULL then gd_Text doesn't contain a pointer to string but an offset
  167.     of the string pointer in given array with pointers to text in foreign
  168.     languages.
  169.  
  170. VOID IFreeGadgets(APTR gl)
  171.     gl - pointer to internal data structure returned by ICreateGadgets
  172.  
  173.     Releases memory for internal data structure allocated by
  174.     ICreateGadgets. If gadgets are currently displayed then they MUST be
  175.     removed with IRemoveGadgets first.
  176.  
  177. VOID IDisplayGadgets(struct Window  *win, APTR gl)
  178.     win - pointer to window opened by (I)OpenWindow
  179.     gl - pointer to internal data structure returned by ICreateGadgets
  180.  
  181.     Displays all gadgets from given internal data structure (gadgets now
  182.     are selectable). To remove gadgets from display use IRemoveGadgets
  183.     (gadgets aren't selectable any more).
  184.  
  185. VOID IRefreshGadgets(APTR gl)
  186.     gl - pointer to internal data structure returned by ICreateGadgets
  187.  
  188.     Refresh images of all gadgets from given internal data structure.
  189.  
  190. VOID IModifyGadget(APTR gl, USHORT data_entry, LONG left_edge, LONG top_edge,
  191.                           ULONG width, ULONG height)
  192.     gl - pointer to internal data structure returned by ICreateGadgets
  193.     data_entry - offset (in array of GadgetData structures) of gadget to
  194.              modify
  195.     left_edge, top_edge, width, height - new dimension of gadget or
  196.                          USE_CURRENT_VALUE for old value
  197.  
  198.     Repositions and/or resizes a gadget. All gadgets can be repositioned
  199.     but only some gadgets can be modified: buttons, sliders and
  200.     scrollers.
  201.  
  202. ULONG ISetGadgetAttributes(APTR gl, USHORT data_entry, ULONG flag_mask,
  203.              ULONG flag_bits, ULONG data1, ULONG data2, VOID *data3)
  204.     gl - pointer to internal data structure returned by ICreateGadgets
  205.     data_entry - offset (in array of GadgetData structures) of gadget to
  206.              change attributes
  207.     flag_mask - mask with bits set for flag bits to change
  208.     flag_bits - new flag bits (only bits with flag mask bit set are
  209.             changed)
  210.     data1, data2, data3 - new values for appropriate union gd_SpecialData
  211.                   or USE_CURENT_VALUE for old value
  212.  
  213.     Changes flags or special data of a gadget. Not all special data
  214.     members can be changed of different gadgets. Some are fixed while
  215.     creating.
  216.  
  217. VOID IActivateInputGadget(APTR gl, USHORT data_entry)
  218.     gl - pointer to internal data structure returned by ICreateGadgets
  219.     data_entry - offset (in array of GadgetData structures) of gadget to
  220.              activate
  221.  
  222.     Activates an input gadget (string or integer gadget).
  223.  
  224. struct Gadget  *IGadgetAddress(APTR gl, USHORT data_entry)
  225.     gl - pointer to internal data structure returned by ICreateGadgets
  226.     data_entry - offset (in array of GadgetData structures) of gadget to
  227.              get pointer of its standard gadget structure
  228.  
  229.     Returns pointer to the appropriate standard gadget structure.
  230.  
  231. struct Window  *IRemoveGadgets(APTR gl)
  232.     gl - pointer to internal data structure returned by ICreateGadgets
  233.  
  234.     Removes all gadgets belonging to given internal data structure from
  235.     display (gadgets aren't selectable any more). Pointer to window
  236.     gadgets displayed before is returned.
  237.  
  238. struct IntuiMessage  *IGetMsg(struct MsgPort  *uport)
  239.     uport - window's user port
  240.  
  241.     MUST be used instead of Exec's GetMsg to handle all actions belonging
  242.     to ISUP objects. For all events produced by ISUP objects a modified
  243.     IntuiMessage structure will be returned. It's member Class is
  244.     set to ISUP_ID. The member Code contains the offset (in array of
  245.     GadgetData structures) of appropriate gadget and in member IAddress
  246.     resides the value returned from gadget. All special IntuiMessage
  247.     structures MUST be replied with IReplyMsg instead of Exec's ReplyMsg.
  248.  
  249.     Example:
  250.  
  251.        struct IntuiMessage *im;
  252.  
  253.        while (im = IGetMsg(win->UserPort)) {
  254.                ^
  255.                |
  256.           if (im->Class == ISUP_ID) {
  257.          ULONG value;
  258.  
  259.          /* Handle event from ISUP object */
  260.          switch (im->Code) {
  261.             case 0 :    /* first object in GadgetData array */
  262.                value = (ULONG)im->IAddress;   /* value returned from this object */
  263.                break;
  264.                  :
  265.                  :
  266.             case n :    /* n-th object in GadgetData array */
  267.                value = (ULONG)im->IAddress;   /* value returned from this object */
  268.                break;
  269.          }
  270.           }
  271.           IReplyMsg(im);
  272.           ^
  273.           |
  274.        }
  275.  
  276. VOID IReplyMsg(struct IntuiMessage  *imsg)
  277.     imsg - IntuiMessage received with IGetMsg
  278.  
  279.     Replys special IntuiMessage built by IGetMsg.
  280.  
  281. BOOL IAutoRequest(struct Window  *req_win, BYTE *title, BYTE *body_text,
  282.                BYTE *pos_text, BYTE *neg_text, LONG pos_idcmp_flags,
  283.      LONG neg_idcmp_flags, USHORT req_flags, BYTE **language_text_array)
  284.     req_win - pointer to window opened by (I)OpenWindow or NULL for
  285.           window on workbench screen
  286.     title - pointer to title string for requester window or NULL for
  287.         default title
  288.     body_text - pointer to text string for requester body
  289.     pos_text - pointer to text string for positive gadget or NULL for no
  290.            positive gadget
  291.     neg_text - pointer to text string for negative gadget or NULL for no
  292.            negative gadget
  293.     pos_idcmp_flags - IDCMP flags for activating positive gadget
  294.     neg_idcmp_flags - IDCMP flags for activating negative gadget
  295.     req_flags - REQ_DATA_FLAG_xxx
  296.     language_text_array - pointer to string pointer array created with
  297.                   IBuildLanguageTextArray or NULL
  298.  
  299.     Displays an auto requester from given data and waits for it's
  300.     termination with the positive or negative gadget. In body text a new
  301.     line is started with `\n'. If given language_text_array is not NULL
  302.     then td_Text doesn't contain a pointer to string but an offset of
  303.     the string pointer in given array with pointers to text in foreign
  304.     languages.
  305.  
  306. APTR IDisplayRequester(struct Window  *req_win, struct RequesterData  *rd,
  307.                          BYTE **language_text_array)
  308.     req_win - pointer to window opened by (I)OpenWindow or NULL for
  309.           window on workbench screen
  310.     rd - pointer to initialized RequesterData structure
  311.     language_text_array - pointer to string pointer array created with
  312.                   IBuildLanguageTextArray or NULL
  313.  
  314.     Displays a requester defined by given RequesterData structure. All
  315.     other gadgets displayed on window the requester window (req_win)
  316.     opened from are disabled till removing of requester. So any
  317.     IntuiMessages with Class == ISUP_ID received by
  318.     IGetMsg(req_win->UserPort) come from requester. If given
  319.     language_text_array is not NULL then td_Text doesn't contain a
  320.     pointer to string but an offset of the string pointer in given array
  321.     with pointers to text in foreign languages. Pointer to internal
  322.     data structure belonging to requester is returned. Requester MUST be
  323.     removed from display with IRemoveRequester.
  324.  
  325. VOID IRemoveRequester(APTR rl)
  326.     rl - pointer to internal data structure returned by IDisplayRequester
  327.  
  328.     Removes requester belonging to given internal data structure from
  329.     display. All gadgets disabled by IDisplayGadgets are reenabled now.
  330.     
  331. APTR ICreateMenu(APTR ri, struct Window  *win, struct MenuData  *md,
  332.                struct TextAttr  *ta, BYTE **language_text_array)
  333.     ri - pointer to internal data structure returned by IGetRenderInfo
  334.     win - pointer to window opened by (I)OpenWindow
  335.     md - pointer to ARRAY of initialized MenuData structures
  336.     ta - pointer to initialized structure with text attributes
  337.     language_text_array - pointer to string pointer array created with
  338.                   IBuildLanguageTextArray or NULL
  339.  
  340.     Create internal data structure for a menu from given array of data
  341.     structures. This function DON'T display the menu. Displaying will be
  342.     done with IAttachMenu. Internal data structure MUST be released with
  343.     IFreeMenu. If given language_text_array are not NULL then md_Text
  344.     doesn't contain a pointer to string but an offset of the string
  345.     pointer in given array with pointers to text in foreign languages.
  346.     Pointer to internal data structure belonging to menu is returned.
  347.  
  348. VOID IAttachMenu(struct Window  *win, APTR ml)
  349.     win - pointer to window opened by (I)OpenWindow
  350.     ml - pointer to internal data structure returned by ICreateMenu
  351.  
  352.     Make menu built with ICreateMenu available by attaching it to given
  353.     window. Menu MUST be removed with IRemoveMenu.
  354.  
  355. struct MenuItem  *IMenuItemAddress(APTR ml, USHORT menu_num)
  356.     ml - pointer to internal data structure returned by ICreateMenu
  357.     menu_num - offset (in array of MenuData structures) of menu item
  358.            to get address
  359.  
  360.     Return pointer to normal MenuItem structure of specified menu item.
  361.  
  362. struct Window  *IRemoveMenu(APTR ml)
  363.     ml - pointer to internal data structure returned by ICreateMenu
  364.  
  365.     Remove menu attached with IAttachMenu from display.
  366.  
  367. VOID IFreeMenu(APTR ml)
  368.     ml - pointer to internal data structure returned by ICreateMenu
  369.  
  370.     Releases memory for internal data structure allocated by
  371.     ICreateMenu. If menu is currently attached then it MUST be removed
  372.     with IRemoveMenu first.
  373.  
  374. struct FileData  *IOpenTextFile(BYTE *name, USHORT read_buffer_size,
  375.                       USHORT line_buffer_size, USHORT flags)
  376.     name - pointer to string with file name
  377.     read_buffer_size - size (in bytes) of buffer used for reading text
  378.                file
  379.     line_buffer_size - number of bytes used for longest line of text
  380.     flags - TEXT_FILE_FLAG_xxx
  381.  
  382.     Opens given text file and returns pointer to data structure with
  383.     allocated buffers. This structure MUST be freed with ICloseTextFile.
  384.  
  385. SHORT IReadTextLine(struct FileData  *fd)
  386.     fd - pointer to internal data structure returned by IOpenTextFile
  387.  
  388.     Read next line from text file opened with IOpenTextFile. This line
  389.     can be found in given FileData structure.
  390.  
  391. VOID ICloseTextFile(struct FileData  *fd)
  392.     fd - pointer to internal data structure returned by IOpenTextFile
  393.  
  394.     Close text file opened with IOpenTextFile and releases allocated
  395.     buffers.
  396.  
  397. BYTE **IBuildLanguageTextArray(BYTE *name, USHORT entries)
  398.     name - pointer to string with name of file with language texts
  399.     entries - number of text entries in file
  400.  
  401.     Parse given text file and return pointer to array of text strings
  402.     read from language file. This array MUST be released with
  403.     IFreeLanguageTextArray.
  404.  
  405. BYTE *IGetLanguageText(BYTE *text, BYTE **text_array)
  406.     text - offset (in array of text strings) of language text (starting
  407.            with 1 instead of 0!!!)
  408.     text_array - pointer to array of text strings created by
  409.              IBuildLanguageTextArray
  410.  
  411.     Returns specified entry from within text pointer array created with
  412.     IBuildLanguageTextArray.
  413.  
  414. VOID IFreeLanguageTextArray(BYTE **text_array)
  415.     text_array - pointer to array of text strings created by
  416.              IBuildLanguageTextArray
  417.  
  418.     Releases memory of array created with IBuildLanguageTextArray.
  419.  
  420. VOID IChangeMousePointer(struct Window  *win, struct PointerData  *pd)
  421.     win - pointer to window opened by (I)OpenWindow
  422.     pd - pointer to initialized PointerData structure or NULL for
  423.          busy mouse pointer
  424.  
  425.     Replace current mouse pointer of selected window with one described
  426.     in given data structure. Old mouse pointer will be saved and can be
  427.     restored later with IRestoreMousePointer.
  428.  
  429. VOID IRestoreMousePointer(struct Window  *win)
  430.     win - pointer to window opened by (I)OpenWindow
  431.  
  432.     Restore old mouse pointer saved with IChangeMousePointer.
  433.  
  434. VOID IMoveMousePointer(struct Window  *win, SHORT x, SHORT y, BOOL button)
  435.     win - pointer to window opened by (I)OpenWindow
  436.     x, y - new position (relative to upper left corner of given
  437.            window!!!) for mouse pointer
  438.     button - TRUE for left mouse button pressed
  439.  
  440.     Move mouse pointer of given window to new position.
  441.